/*!
 * \file ITraderApi.h
 * \project	WonderTrader
 *
 * \author Wesley
 * \date 2020/03/30
 * 
 * \brief 交易接口定义文件
 * 
 * \details 该文件定义了WonderTrader系统中所有交易相关的接口，包括：
 *          - 统一交易接口（ITraderApi）：支持期货、股票、期权等多种品种
 *          - 交易回调接口（ITraderSpi）：处理交易事件和响应
 *          - 股票交易接口（IStkTraderApi）：专门处理股票交易
 *          - 期权交易接口（IOptTraderApi）：专门处理期权交易
 *          
 *          这些接口为量化交易策略提供了统一的交易执行能力，支持：
 *          - 多种交易品种（期货、股票、期权、债券等）
 *          - 完整的交易生命周期管理
 *          - 实时的交易状态监控
 *          - 统一的错误处理机制
 *          - 灵活的交易适配器架构
 */
#pragma once
#include <set>
#include <map>
#include <stdint.h>
#include <functional>
#include "WTSTypes.h"

NS_WTP_BEGIN
class WTSVariant;
class WTSEntrust;
class WTSOrderInfo;
class WTSTradeInfo;
class WTSEntrustAction;
class WTSAccountInfo;
class WTSPositionItem;
class WTSContractInfo;
class WTSError;
class WTSTickData;
class WTSNotify;
class WTSArray;
class IBaseDataMgr;

/*!
 * \typedef CommonExecuter
 * \brief 通用执行器函数类型定义
 * 
 * \details 用于定义无参数无返回值的通用执行函数类型，
 *          常用于异步执行任务和回调处理。
 */
typedef std::function<void()>	CommonExecuter;

#pragma region "Stock Trading API definations"

/*!
 * \class IStkTraderSpi
 * \brief 股票交易接口回调
 * 
 * \details 股票交易相关的回调接口，用于处理股票交易特有的事件：
 *          - 股票下单响应
 *          - 股票订单状态变化
 *          - 股票成交回报
 *          - 股票持仓变化等
 * 
 * \note 该接口为预留接口，当前版本暂未完全实现
 * \see IStkTraderApi
 * \author Wesley
 * \date 2020/05/06
 */
class IStkTraderSpi
{

};

/*!
 * \class IStkTraderApi
 * \brief 股票交易接口
 * 
 * \details 专门用于股票交易的API接口，提供股票特有的交易功能：
 *          - 股票买卖下单
 *          - 股票订单管理
 *          - 股票持仓查询
 *          - 股票资金查询
 *          - 股票交易规则处理
 * 
 * \note 该接口为预留接口，主要用于支持股票、债券等现货品种
 * \warning 当前版本接口定义尚未完善，后续版本会逐步完善相关功能
 * \see ITraderApi, IStkTraderSpi
 * \author Wesley
 * \date 2020/05/06
 */
class IStkTraderApi
{
};
#pragma endregion

#pragma region "Option Trading API definations"

/*!
 * \class IOptTraderSpi
 * \brief 期权交易接口回调
 * 
 * \details 期权交易相关的回调接口，处理期权交易特有的事件和响应：
 *          - 期权下单响应处理
 *          - 期权订单状态监控
 *          - 期权成交回报处理
 *          - 期权持仓变化通知
 * 
 * \note 该接口主要用于股票期权、商品期权、ETF期权等衍生品交易
 * \see IOptTraderApi
 * \author Wesley
 * \date 2020/05/06
 */
class IOptTraderSpi
{
public:
	/*!
	 * \brief 期权下单响应回调
	 * \param[in] entrust 委托订单信息
	 * \param[in] err 错误信息，如果成功则为NULL
	 * 
	 * \details 当期权下单请求得到交易所响应时被调用：
	 *          - 成功：entrust包含订单信息，err为NULL
	 *          - 失败：err包含具体错误信息
	 */
	virtual void onRspEntrustOpt(WTSEntrust* entrust, WTSError *err) {}
	
	/*!
	 * \brief 期权订单查询响应回调
	 * \param[in] ayOrders 订单列表数组
	 * 
	 * \details 响应期权订单查询请求，返回当前所有期权订单信息
	 */
	virtual void onRspOrdersOpt(const WTSArray* ayOrders) {}
	
	/*!
	 * \brief 期权订单状态推送回调
	 * \param[in] orderInfo 订单状态信息
	 * 
	 * \details 当期权订单状态发生变化时主动推送：
	 *          - 订单确认
	 *          - 部分成交
	 *          - 全部成交
	 *          - 订单撤销等
	 */
	virtual void onPushOrderOpt(WTSOrderInfo* orderInfo) {}
};

/*!
 * \class IOptTraderApi
 * \brief 期权交易接口
 * 
 * \details 专门用于期权交易的API接口，提供期权特有的交易功能：
 *          - 期权买入/卖出开仓
 *          - 期权买入/卖出平仓
 *          - 期权行权操作
 *          - 期权组合策略
 *          - 期权风险管理
 * 
 * \note 支持股票期权、商品期权、ETF期权等多种期权品种
 * \see IOptTraderSpi, ITraderApi
 * \author Wesley
 * \date 2020/05/06
 */
class IOptTraderApi
{
public:
	/*!
	 * \brief 期权下单接口
	 * \param[in] eutrust 下单的具体委托数据结构
	 * \return 操作结果：0表示成功，负数表示失败
	 * 
	 * \details 提交期权买卖订单：
	 *          - 支持期权开仓和平仓
	 *          - 支持期权买入和卖出
	 *          - 支持期权行权操作
	 * 
	 * \note 默认返回-1表示接口未实现，子类需要重写
	 */
	virtual int orderInsertOpt(WTSEntrust* eutrust) { return -1; }

	/*!
	 * \brief 期权撤单接口
	 * \param[in] action 撤单的具体委托数据结构
	 * \return 操作结果：0表示成功，负数表示失败
	 * 
	 * \details 撤销指定的期权订单：
	 *          - 根据订单ID进行撤单
	 *          - 支持部分撤单和全部撤单
	 *          - 提供撤单失败的详细原因
	 */
	virtual int orderActionOpt(WTSEntrustAction* action) { return -1; }

	/*!
	 * \brief 查询期权订单
	 * \param[in] bType 业务类型
	 * \return 操作结果：0表示成功，负数表示失败
	 * 
	 * \details 查询当前账户的期权订单信息：
	 *          - 未成交订单
	 *          - 部分成交订单
	 *          - 已成交订单
	 *          - 已撤销订单等
	 */
	virtual int	queryOrdersOpt(WTSBusinessType bType) { return -1; }
};
#pragma endregion

/*!
 * \class ITraderSpi
 * \brief 交易接口回调
 * 
 * \details 交易API的回调接口，用于处理各种交易事件和响应：
 * 
 * **主要功能：**
 * - **连接管理**: 处理登录、登出、连接状态变化
 * - **订单管理**: 处理下单响应、订单状态变化、成交回报
 * - **查询响应**: 处理账户、持仓、订单、成交等查询结果
 * - **错误处理**: 统一的错误信息处理机制
 * - **事件通知**: 处理交易相关的各种事件通知
 * 
 * **回调类型：**
 * - **同步响应**: 对查询请求的直接响应
 * - **异步推送**: 交易所主动推送的实时信息
 * - **错误通知**: 各种异常和错误的通知
 * 
 * \note 该接口是交易系统的核心回调接口，所有交易适配器都需要实现
 * \see ITraderApi
 */
class ITraderSpi
{
public:
	/*!
	 * \brief 获取基础数据管理器
	 * \return 基础数据管理器指针
	 * 
	 * \details 返回基础数据管理器实例，用于获取合约信息、交易日历等基础数据
	 */
	virtual IBaseDataMgr*	getBaseDataMgr() = 0;
	
	/*!
	 * \brief 处理交易日志
	 * \param[in] ll 日志级别
	 * \param[in] message 日志消息
	 * 
	 * \details 处理来自交易适配器的日志信息：
	 *          - 调试信息
	 *          - 警告信息
	 *          - 错误信息
	 *          - 系统状态信息
	 * 
	 * \note 默认为空实现，子类可根据需要重写
	 */
	virtual void handleTraderLog(WTSLogLevel ll, const char* message){}

	/*!
	 * \brief 获取股票交易回调接口
	 * \return 股票交易回调接口指针，默认返回NULL
	 * 
	 * \details 如果需要处理股票交易特有的回调，可重写此方法返回具体实现
	 */
	virtual IStkTraderSpi* getStkSpi(){ return NULL; }
	
	/*!
	 * \brief 获取期权交易回调接口
	 * \return 期权交易回调接口指针，默认返回NULL
	 * 
	 * \details 如果需要处理期权交易特有的回调，可重写此方法返回具体实现
	 */
	virtual IOptTraderSpi* getOptSpi(){ return NULL; }

public:
	/*!
	 * \brief 处理交易事件
	 * \param[in] e 交易事件类型
	 * \param[in] ec 事件代码
	 * 
	 * \details 处理各种交易相关事件：
	 *          - 连接建立/断开
	 *          - 登录成功/失败
	 *          - 交易时段开始/结束
	 *          - 系统维护通知等
	 */
	virtual void handleEvent(WTSTraderEvent e, int32_t ec) = 0;
	
	/*!
	 * \brief 登录结果回调
	 * \param[in] bSucc 是否登录成功
	 * \param[in] msg 登录信息或错误描述
	 * \param[in] tradingdate 交易日期
	 * 
	 * \details 交易系统登录完成后的结果通知：
	 *          - 成功：bSucc=true，msg包含欢迎信息
	 *          - 失败：bSucc=false，msg包含失败原因
	 */
	virtual void onLoginResult(bool bSucc, const char* msg, uint32_t tradingdate) = 0;
	
	/*!
	 * \brief 登出回调
	 * 
	 * \details 交易系统登出完成时被调用，用于清理相关资源
	 * 
	 * \note 默认为空实现，子类可根据需要重写
	 */
	virtual void onLogout(){}
	
	/*!
	 * \brief 下单响应回调
	 * \param[in] entrust 委托订单信息
	 * \param[in] err 错误信息，如果成功则为NULL
	 * 
	 * \details 当下单请求得到交易所响应时被调用：
	 *          - 成功：entrust包含确认的订单信息
	 *          - 失败：err包含具体的失败原因
	 * 
	 * \note 默认为空实现，子类可根据需要重写
	 */
	virtual void onRspEntrust(WTSEntrust* entrust, WTSError *err){}
	
	/*!
	 * \brief 账户查询响应回调
	 * \param[in] ayAccounts 账户信息数组
	 * 
	 * \details 响应账户查询请求，返回账户资金、保证金等信息：
	 *          - 可用资金
	 *          - 冻结资金
	 *          - 总资产
	 *          - 盈亏情况等
	 * 
	 * \note 默认为空实现，子类可根据需要重写
	 */
	virtual void onRspAccount(WTSArray* ayAccounts) {}
	
	/*!
	 * \brief 持仓查询响应回调
	 * \param[in] ayPositions 持仓信息数组
	 * 
	 * \details 响应持仓查询请求，返回当前所有持仓信息：
	 *          - 合约代码和名称
	 *          - 持仓方向和数量
	 *          - 开仓价格和成本
	 *          - 当前盈亏等
	 * 
	 * \note 默认为空实现，子类可根据需要重写
	 */
	virtual void onRspPosition(const WTSArray* ayPositions){}
	
	/*!
	 * \brief 订单查询响应回调
	 * \param[in] ayOrders 订单信息数组
	 * 
	 * \details 响应订单查询请求，返回当前所有订单信息：
	 *          - 订单状态
	 *          - 成交数量
	 *          - 剩余数量
	 *          - 订单时间等
	 * 
	 * \note 默认为空实现，子类可根据需要重写
	 */
	virtual void onRspOrders(const WTSArray* ayOrders){}
	
	/*!
	 * \brief 成交查询响应回调
	 * \param[in] ayTrades 成交信息数组
	 * 
	 * \details 响应成交查询请求，返回当前所有成交记录：
	 *          - 成交价格和数量
	 *          - 成交时间
	 *          - 手续费
	 *          - 对应订单信息等
	 * 
	 * \note 默认为空实现，子类可根据需要重写
	 */
	virtual void onRspTrades(const WTSArray* ayTrades){}
	
	/*!
	 * \brief 结算单查询响应回调
	 * \param[in] uDate 结算日期
	 * \param[in] content 结算单内容
	 * 
	 * \details 响应结算单查询请求，返回指定日期的结算单内容
	 * 
	 * \note 默认为空实现，子类可根据需要重写
	 */
	virtual void onRspSettlementInfo(uint32_t uDate, const char* content){}

	/*!
	 * \brief 订单状态推送回调
	 * \param[in] orderInfo 订单状态信息
	 * 
	 * \details 当订单状态发生变化时主动推送：
	 *          - 订单确认
	 *          - 部分成交
	 *          - 全部成交
	 *          - 订单撤销
	 *          - 订单拒绝等
	 * 
	 * \note 默认为空实现，子类可根据需要重写
	 */
	virtual void onPushOrder(WTSOrderInfo* orderInfo){}
	
	/*!
	 * \brief 成交推送回调
	 * \param[in] tradeRecord 成交记录信息
	 * 
	 * \details 当有新的成交发生时主动推送成交信息：
	 *          - 实时成交通知
	 *          - 成交价格和数量
	 *          - 手续费计算
	 *          - 持仓变化等
	 * 
	 * \note 默认为空实现，子类可根据需要重写
	 */
	virtual void onPushTrade(WTSTradeInfo* tradeRecord){}

	/*!
	 * \brief 交易错误回调
	 * \param[in] err 错误信息
	 * 
	 * \details 当交易过程中发生错误时被调用：
	 *          - 网络连接错误
	 *          - 交易权限错误
	 *          - 风控限制错误
	 *          - 系统内部错误等
	 * 
	 * \note 默认为空实现，子类可根据需要重写
	 */
	virtual void onTraderError(WTSError* err){}
};

/*!
 * \class ITraderApi
 * \brief 交易接口
 * 
 * \details 统一的交易API接口，提供完整的交易功能：
 * 
 * **核心功能：**
 * - **连接管理**: 建立和维护与交易系统的连接
 * - **身份认证**: 用户登录、权限验证、会话管理
 * - **订单管理**: 下单、撤单、改单、查询等完整的订单生命周期管理
 * - **查询服务**: 账户、持仓、订单、成交、结算单等信息查询
 * - **实时推送**: 订单状态、成交回报等实时信息推送
 * 
 * **支持品种：**
 * - 商品期货和金融期货
 * - 股票和ETF
 * - 期权（股票期权、商品期权等）
 * - 债券和可转债
 * 
 * **技术特性：**
 * - 统一的接口设计，支持多种交易系统
 * - 异步处理机制，保证高性能
 * - 完善的错误处理和重连机制
 * - 灵活的适配器架构，便于扩展
 * 
 * \note 该接口为纯虚接口，具体实现由各交易适配器提供
 * \see ITraderSpi
 */
class ITraderApi
{
public:
	/*!
	 * \brief 虚析构函数
	 * 
	 * \details 确保派生类能够正确析构，释放相关资源
	 */
	virtual ~ITraderApi(){}

	/*!
	 * \brief 获取股票交易接口
	 * \return 股票交易接口指针，默认返回NULL
	 * 
	 * \details 如果交易适配器支持股票交易，可重写此方法返回股票交易接口实例
	 */
	virtual IStkTraderApi* getStkTrader() { return NULL; }
	
	/*!
	 * \brief 获取期权交易接口
	 * \return 期权交易接口指针，默认返回NULL
	 * 
	 * \details 如果交易适配器支持期权交易，可重写此方法返回期权交易接口实例
	 */
	virtual IOptTraderApi* getOptTrader() { return NULL; }

public:
	/*!
	 * \brief 初始化交易接口
	 * \param[in] params 初始化参数
	 * \return 初始化是否成功
	 * 
	 * \details 使用指定参数初始化交易接口：
	 *          - 解析配置参数
	 *          - 初始化网络连接
	 *          - 设置交易环境
	 *          - 准备认证信息等
	 * 
	 * \note 默认返回false，子类必须重写实现具体的初始化逻辑
	 */
	virtual bool init(WTSVariant *params) { return false; }

	/*!
	 * \brief 释放交易接口
	 * 
	 * \details 释放交易接口相关资源：
	 *          - 断开网络连接
	 *          - 清理内存资源
	 *          - 保存必要的状态信息
	 * 
	 * \note 默认为空实现，子类应重写实现具体的资源清理逻辑
	 */
	virtual void release(){}

	/*!
	 * \brief 注册回调接口
	 * \param[in] listener 回调接口实现
	 * 
	 * \details 注册交易事件回调接口，用于接收各种交易事件和响应
	 * 
	 * \note 默认为空实现，子类应重写实现回调注册逻辑
	 */
	virtual void registerSpi(ITraderSpi *listener) {}


	//////////////////////////////////////////////////////////////////////////
	//业务逻辑接口

	/*!
	 * \brief 连接服务器
	 * 
	 * \details 建立与交易服务器的网络连接：
	 *          - TCP连接建立
	 *          - 心跳机制启动
	 *          - 连接状态监控
	 * 
	 * \note 默认为空实现，子类应重写实现具体的连接逻辑
	 */
	virtual void connect() {}

	/*!
	 * \brief 断开连接
	 * 
	 * \details 主动断开与交易服务器的连接：
	 *          - 停止心跳机制
	 *          - 关闭网络连接
	 *          - 清理连接状态
	 * 
	 * \note 默认为空实现，子类应重写实现具体的断开逻辑
	 */
	virtual void disconnect() {}

	/*!
	 * \brief 检查连接状态
	 * \return 是否已连接
	 * 
	 * \details 检查当前与交易服务器的连接状态
	 * 
	 * \note 默认返回false，子类应重写实现状态检查逻辑
	 */
	virtual bool isConnected() { return false; }

	/*!
	 * \brief 生成委托单号
	 * \param[out] buffer 输出缓冲区
	 * \param[in] length 缓冲区长度
	 * \return 是否生成成功
	 * 
	 * \details 生成唯一的委托单号，用于标识每笔交易订单：
	 *          - 保证全局唯一性
	 *          - 便于订单跟踪
	 *          - 支持订单关联
	 * 
	 * \note 默认返回false，子类应重写实现委托单号生成逻辑
	 */
	virtual bool makeEntrustID(char* buffer, int length){ return false; }

	/*!
	 * \brief 登录接口
	 * \param[in] user 用户名
	 * \param[in] pass 密码
	 * \param[in] productInfo 产品信息
	 * \return 登录请求结果：0表示成功，负数表示失败
	 * 
	 * \details 向交易系统发送登录请求：
	 *          - 用户身份验证
	 *          - 交易权限检查
	 *          - 会话建立
	 *          - 获取交易日期等
	 * 
	 * \note 默认返回-1，子类应重写实现具体的登录逻辑
	 */
	virtual int login(const char* user, const char* pass, const char* productInfo) { return -1; }

	/*!
	 * \brief 注销接口
	 * \return 注销请求结果：0表示成功，负数表示失败
	 * 
	 * \details 向交易系统发送注销请求，安全退出交易会话
	 * 
	 * \note 默认返回-1，子类应重写实现具体的注销逻辑
	 */
	virtual int logout() { return -1; }

	/*!
	 * \brief 下单接口
	 * \param[in] eutrust 下单的具体委托数据结构
	 * \return 下单请求结果：0表示成功，负数表示失败
	 * 
	 * \details 向交易系统提交新订单：
	 *          - 订单合法性检查
	 *          - 风控规则验证
	 *          - 发送到交易所
	 *          - 返回订单确认
	 * 
	 * \note 默认返回-1，子类应重写实现具体的下单逻辑
	 */
	virtual int orderInsert(WTSEntrust* eutrust) { return -1; }

	/*!
	 * \brief 撤单接口
	 * \param[in] action 撤单的具体委托数据结构
	 * \return 撤单请求结果：0表示成功，负数表示失败
	 * 
	 * \details 向交易系统提交撤单请求：
	 *          - 根据订单ID定位订单
	 *          - 检查撤单权限
	 *          - 发送撤单指令
	 *          - 返回撤单确认
	 * 
	 * \note 默认返回-1，子类应重写实现具体的撤单逻辑
	 */
	virtual int orderAction(WTSEntrustAction* action) { return -1; }

	/*!
	 * \brief 查询账户信息
	 * \return 查询请求结果：0表示成功，负数表示失败
	 * 
	 * \details 查询当前账户的资金信息：
	 *          - 可用资金
	 *          - 冻结资金
	 *          - 总资产
	 *          - 当日盈亏等
	 * 
	 * \note 默认返回-1，子类应重写实现具体的查询逻辑
	 */
	virtual int queryAccount() { return -1; }

	/*!
	 * \brief 查询持仓信息
	 * \return 查询请求结果：0表示成功，负数表示失败
	 * 
	 * \details 查询当前账户的持仓信息：
	 *          - 所有合约的持仓情况
	 *          - 持仓方向和数量
	 *          - 开仓成本和当前盈亏
	 *          - 保证金占用等
	 * 
	 * \note 默认返回-1，子类应重写实现具体的查询逻辑
	 */
	virtual int queryPositions() { return -1; }

	/*!
	 * \brief 查询当日订单
	 * \return 查询请求结果：0表示成功，负数表示失败
	 * 
	 * \details 查询当日所有订单信息：
	 *          - 订单状态（未成交、部分成交、全部成交、已撤销等）
	 *          - 订单详情（价格、数量、时间等）
	 *          - 成交情况统计
	 * 
	 * \note 默认返回-1，子类应重写实现具体的查询逻辑
	 */
	virtual int queryOrders() { return -1; }

	/*!
	 * \brief 查询成交明细
	 * \return 查询请求结果：0表示成功，负数表示失败
	 * 
	 * \details 查询当日所有成交记录：
	 *          - 成交价格和数量
	 *          - 成交时间
	 *          - 对应的订单信息
	 *          - 手续费明细等
	 * 
	 * \note 默认返回-1，子类应重写实现具体的查询逻辑
	 */
	virtual int	queryTrades() { return -1; }

	/*!
	 * \brief 查询结算单
	 * \param[in] uDate 查询日期，格式为YYYYMMDD
	 * \return 查询请求结果：0表示成功，负数表示失败
	 * 
	 * \details 查询指定日期的结算单信息：
	 *          - 当日交易汇总
	 *          - 盈亏计算
	 *          - 手续费统计
	 *          - 资金变动情况等
	 * 
	 * \note 默认返回0，子类可重写实现具体的查询逻辑
	 */
	virtual int querySettlement(uint32_t uDate){ return 0; }

};

NS_WTP_END

/*!
 * \typedef FuncCreateTrader
 * \brief 创建交易接口的函数指针类型
 * 
 * \details 用于动态加载交易适配器时创建交易接口实例的函数指针类型
 */
typedef wtp::ITraderApi* (*FuncCreateTrader)();

/*!
 * \typedef FuncDeleteTrader
 * \brief 删除交易接口的函数指针类型
 * 
 * \details 用于动态加载交易适配器时销毁交易接口实例的函数指针类型
 */
typedef void(*FuncDeleteTrader)(wtp::ITraderApi* &trader);
